Skip to content

docs(gfql): add temporal predicates documentation and notebook CI testing#674

Closed
lmeyerov wants to merge 22 commits into
fix/temporal-type-errors-cleanfrom
docs/gfql-temporal-predicates
Closed

docs(gfql): add temporal predicates documentation and notebook CI testing#674
lmeyerov wants to merge 22 commits into
fix/temporal-type-errors-cleanfrom
docs/gfql-temporal-predicates

Conversation

@lmeyerov

@lmeyerov lmeyerov commented Jun 23, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

This PR adds comprehensive documentation for GFQL temporal predicates and introduces notebook CI testing infrastructure.

Changes

Documentation

  • GFQL Temporal Predicates Documentation (from previous commits in this branch):
    • Added datetime filtering guide with comprehensive examples
    • Added wire protocol reference for temporal value serialization
    • Added temporal_predicates.ipynb demonstrating date/time filtering with pandas/numpy datetime types
    • Shows usage of gt, lt, between, is_in with temporal values
    • Demonstrates timezone-aware filtering and wire protocol dict usage

CI Infrastructure

  • Notebook Testing Framework:
    • Added automated validation for Jupyter notebooks during docs build
    • Structure validation: Ensures notebooks have required fields (e.g., execution_count)
    • Execution validation: Optionally verifies notebooks run without errors
    • Currently validates temporal_predicates.ipynb and layout_tree.ipynb
    • Integrated into GitHub Actions CI pipeline

Fixes

  • Fixed temporal_predicates.ipynb structure (added missing execution_count, removed invalid markdown cell outputs)
  • Fixed pre-existing PlotterBase.py RST docstring formatting errors that were blocking docs build

Build Improvements

  • Added ipykernel==6.29.5 to docs dependencies for notebook execution
  • Updated Dockerfile to register Python kernel during build
  • Changed docs build script from /bin/sh to /bin/bash for array support

Testing

  • Docs build passes with all temporal predicates documentation
  • Notebook structure validation runs on every CI build
  • Selected notebooks don't require .plot() or register() calls, making them suitable for CI validation

Notes

  • This completes the GFQL temporal predicates feature by adding user-facing documentation
  • The notebook CI infrastructure ensures our example notebooks remain valid and executable
  • Additional notebooks can be added to validation as needed

lmeyerov and others added 8 commits June 22, 2025 21:32
@lmeyerov @claude
feat(gfql): add temporal predicates and type system
612036d 
- Add temporal value classes (DateTime, Date, Time) with timezone support
- Extend comparison predicates (GT, LT, GE, LE, EQ, NE, Between) for temporal values
- Enhance IsIn predicate to support temporal values with type validation
- Add comprehensive GFQL type system with guards and coercions
- Include temporal value serialization and wire format support
- Add comprehensive test coverage for temporal operations

Enables date/time comparisons and filtering in GFQL queries.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
fix(gfql): add TypeGuard annotations and TemporalValue to type unions
21e24c3 
- Add TypeGuard import with proper Python version handling
- Add TypeGuard annotation to is_basic_scalar for type narrowing
- Include TemporalValue in ComparisonInput and IsInElementInput unions
- Enables proper type checking for temporal predicates

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
fix(predicates): remove type errors in is_in predicate
0675f2c 
- Remove unnecessary type: ignore comment
- Add proper handling for TemporalValue in _normalize_value
- Type narrowing now works correctly with TypeGuard

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
refactor(predicates): inline temporal comparison logic into operators
de477f2 
- Remove monolithic _temporal_comparison method with operator dispatch
- Add focused helper methods for series preparation and value extraction
- Inline comparison logic directly in each operator (GT, LT, GE, LE, EQ, NE)
- Eliminate all type: ignore and cast statements
- Each operator now clearly shows both numeric and temporal comparison logic

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
docs: update CHANGELOG.md with GFQL temporal predicates feature
0259fab 
🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
docs: list supported temporal comparison operators in CHANGELOG
3b44c62 
🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
docs: add is_in to list of temporal operators in CHANGELOG
08a07bd 
🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
fix(types): support TypeGuard across Python 3.8-3.12
2d3412d 
- Use version check for TypeGuard import only during TYPE_CHECKING
- Remove pd.Series[T] generic syntax not supported in Python 3.8
- Ensures mypy passes on all supported Python versions

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This was referenced Jun 23, 2025
Closed
Merged
lmeyerov and others added 6 commits June 23, 2025 03:16
@lmeyerov @claude
fix(is_in): move dynamic imports to module level
bfa3ca4 
- Move Any import from method-level to module-level
- Move DateTimeWire, DateWire, TimeWire imports to module-level
- Fixes dynamic import issue flagged during code review

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
docs: add temporal predicates documentation
b3e45d2 
- Add temporal_predicates.ipynb demo notebook with TOC and examples
- Add datetime_filtering.md with imports, standards, and duration notes
- Update wire_protocol_examples.md with clearer structure
- Documentation for GFQL temporal predicate features

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
docs: consolidate temporal predicates documentation
f3fcb85 
- Add comprehensive datetime filtering guide
- Add temporal predicates notebook with examples
- Add wire protocol examples for temporal values
- Update GFQL overview with temporal examples
- Update predicates quick reference with temporal operators
- Add temporal modules to API documentation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
docs(gfql): update CHANGELOG with temporal predicates documentation
2dc9cca 
- Add temporal value classes to changelog
- Add wire protocol support mention
- Add documentation references (datetime guide, wire protocol, notebook)

📤 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
fix(docs): update temporal predicates notebook with correct relative …
17cfc66 
…links

- Add datetime_filtering and wire_protocol_examples to GFQL toctree
- Use relative HTML links that work across all hosting environments
- Links go up two levels from demos/gfql/ to reach gfql/ documentation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
fix(docs): correct temporal values module path in API docs
5c44d99 
- Change from non-existent temporal_values module to ast_temporal
- Fixes autodoc import error during documentation build

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov lmeyerov force-pushed the docs/gfql-temporal-predicates branch from 05e93dd to 5c44d99 Compare June 23, 2025 18:30
lmeyerov and others added 4 commits June 23, 2025 14:42
@lmeyerov @claude
docs(gfql): improve temporal predicates documentation clarity
d89d18e 
- Streamline datetime filtering guide with concise examples
- Add clear links to Python/Pandas datetime documentation
- Improve notebook imports with explanatory comments
- Fix broken chain.rst link to use correct path
- Make documentation more actionable with direct type links

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
docs(gfql): remove recommendation language for direct facts
4e47320 
- Remove "recommended" verbiage in favor of direct documentation
- Keep examples factual without good/bad judgments
- Let ordering and examples guide usage naturally

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
docs(gfql): add wire protocol dict support for ISO strings
83e38d1 
- Document that wire protocol dicts are a supported input type
- Show how to use ISO strings via wire protocol dicts
- Clarify that only raw strings raise ValueError

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov @claude
docs(gfql): remove good/bad language from wire protocol examples
d526ca3 
- Replace bad_filter/good_filter with factual variable names
- Keep error handling examples factual without judgments
- Align with direct documentation style

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@lmeyerov lmeyerov changed the title docs(gfql): add temporal predicates documentation docs(gfql): add temporal predicates documentation and notebook CI testing Jun 23, 2025
lmeyerov added 4 commits June 23, 2025 22:36
@lmeyerov
fix(docs): fix temporal_predicates notebook structure
f74a1d7 
- Add missing execution_count field to all code cells
- Remove invalid outputs field from markdown cell
@lmeyerov
feat(docs): add notebook validation to docs build
9558bc3 
- Add structure validation for notebooks during docs build
- Validate temporal_predicates.ipynb and layout_tree.ipynb
- Enable validation in CI with VALIDATE_NOTEBOOK_EXECUTION env var
- Update build script to use bash for array support
@lmeyerov
build(docs): add ipykernel dependency for notebook execution
6fd739a 
- Add ipykernel==6.29.5 to docs dependencies
- Register Python kernel in Dockerfile build step
@lmeyerov
docs: update CHANGELOG with documentation improvements
02e3fd7
@lmeyerov lmeyerov force-pushed the docs/gfql-temporal-predicates branch from e0f0884 to 02e3fd7 Compare June 24, 2025 02:37
@lmeyerov lmeyerov force-pushed the fix/temporal-type-errors-clean branch from bfa3ca4 to edf8508 Compare June 24, 2025 04:03
@lmeyerov lmeyerov closed this Jun 24, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@lmeyerov